// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_PICKLE_H_
#define BASE_PICKLE_H_

#include <stddef.h>
#include <stdint.h>

#include <string>

#include "base/base_export.h"
#include "base/compiler_specific.h"
#include "base/gtest_prod_util.h"
#include "base/logging.h"
#include "base/memory/ref_counted.h"
#include "base/strings/string16.h"
#include "base/strings/string_piece.h"

#if defined(OS_POSIX)
#include "base/files/file.h"
#endif

namespace base {

class Pickle;

// PickleIterator reads data from a Pickle. The Pickle object must remain valid
// while the PickleIterator object is in use.
class BASE_EXPORT PickleIterator {
public:
    PickleIterator()
        : payload_(NULL)
        , read_index_(0)
        , end_index_(0)
    {
    }
    explicit PickleIterator(const Pickle& pickle);

    // Methods for reading the payload of the Pickle. To read from the start of
    // the Pickle, create a PickleIterator from a Pickle. If successful, these
    // methods return true. Otherwise, false is returned to indicate that the
    // result could not be extracted. It is not possible to read from the iterator
    // after that.
    bool ReadBool(bool* result) WARN_UNUSED_RESULT;
    bool ReadInt(int* result) WARN_UNUSED_RESULT;
    bool ReadLong(long* result) WARN_UNUSED_RESULT;
    bool ReadUInt16(uint16_t* result) WARN_UNUSED_RESULT;
    bool ReadUInt32(uint32_t* result) WARN_UNUSED_RESULT;
    bool ReadInt64(int64_t* result) WARN_UNUSED_RESULT;
    bool ReadUInt64(uint64_t* result) WARN_UNUSED_RESULT;
    bool ReadFloat(float* result) WARN_UNUSED_RESULT;
    bool ReadDouble(double* result) WARN_UNUSED_RESULT;
    bool ReadString(std::string* result) WARN_UNUSED_RESULT;
    // The StringPiece data will only be valid for the lifetime of the message.
    bool ReadStringPiece(StringPiece* result) WARN_UNUSED_RESULT;
    bool ReadString16(string16* result) WARN_UNUSED_RESULT;
    // The StringPiece16 data will only be valid for the lifetime of the message.
    bool ReadStringPiece16(StringPiece16* result) WARN_UNUSED_RESULT;

    // A pointer to the data will be placed in |*data|, and the length will be
    // placed in |*length|. The pointer placed into |*data| points into the
    // message's buffer so it will be scoped to the lifetime of the message (or
    // until the message data is mutated). Do not keep the pointer around!
    bool ReadData(const char** data, int* length) WARN_UNUSED_RESULT;

    // A pointer to the data will be placed in |*data|. The caller specifies the
    // number of bytes to read, and ReadBytes will validate this length. The
    // pointer placed into |*data| points into the message's buffer so it will be
    // scoped to the lifetime of the message (or until the message data is
    // mutated). Do not keep the pointer around!
    bool ReadBytes(const char** data, int length) WARN_UNUSED_RESULT;

    // A safer version of ReadInt() that checks for the result not being negative.
    // Use it for reading the object sizes.
    bool ReadLength(int* result) WARN_UNUSED_RESULT
    {
        return ReadInt(result) && *result >= 0;
    }

    // Skips bytes in the read buffer and returns true if there are at least
    // num_bytes available. Otherwise, does nothing and returns false.
    bool SkipBytes(int num_bytes) WARN_UNUSED_RESULT
    {
        return !!GetReadPointerAndAdvance(num_bytes);
    }

private:
    // Read Type from Pickle.
    template <typename Type>
    bool ReadBuiltinType(Type* result);

    // Advance read_index_ but do not allow it to exceed end_index_.
    // Keeps read_index_ aligned.
    void Advance(size_t size);

    // Get read pointer for Type and advance read pointer.
    template <typename Type>
    const char* GetReadPointerAndAdvance();

    // Get read pointer for |num_bytes| and advance read pointer. This method
    // checks num_bytes for negativity and wrapping.
    const char* GetReadPointerAndAdvance(int num_bytes);

    // Get read pointer for (num_elements * size_element) bytes and advance read
    // pointer. This method checks for int overflow, negativity and wrapping.
    const char* GetReadPointerAndAdvance(int num_elements,
        size_t size_element);

    const char* payload_; // Start of our pickle's payload.
    size_t read_index_; // Offset of the next readable byte in payload.
    size_t end_index_; // Payload size.

    FRIEND_TEST_ALL_PREFIXES(PickleTest, GetReadPointerAndAdvance);
};

// This class provides an interface analogous to base::Pickle's WriteFoo()
// methods and can be used to accurately compute the size of a hypothetical
// Pickle's payload without having to reference the Pickle implementation.
class BASE_EXPORT PickleSizer {
public:
    PickleSizer();
    ~PickleSizer();

    // Returns the computed size of the payload.
    size_t payload_size() const { return payload_size_; }

    void AddBool() { return AddInt(); }
    void AddInt() { AddPOD<int>(); }
    void AddLong() { AddPOD<uint64_t>(); }
    void AddUInt16() { return AddPOD<uint16_t>(); }
    void AddUInt32() { return AddPOD<uint32_t>(); }
    void AddInt64() { return AddPOD<int64_t>(); }
    void AddUInt64() { return AddPOD<uint64_t>(); }
    void AddFloat() { return AddPOD<float>(); }
    void AddDouble() { return AddPOD<double>(); }
    void AddString(const StringPiece& value);
    void AddString16(const StringPiece16& value);
    void AddData(int length);
    void AddBytes(int length);
    void AddAttachment();

private:
    // Just like AddBytes() but with a compile-time size for performance.
    template <size_t length>
    void BASE_EXPORT AddBytesStatic();

    template <typename T>
    void AddPOD() { AddBytesStatic<sizeof(T)>(); }

    size_t payload_size_ = 0;
};

// This class provides facilities for basic binary value packing and unpacking.
//
// The Pickle class supports appending primitive values (ints, strings, etc.)
// to a pickle instance.  The Pickle instance grows its internal memory buffer
// dynamically to hold the sequence of primitive values.   The internal memory
// buffer is exposed as the "data" of the Pickle.  This "data" can be passed
// to a Pickle object to initialize it for reading.
//
// When reading from a Pickle object, it is important for the consumer to know
// what value types to read and in what order to read them as the Pickle does
// not keep track of the type of data written to it.
//
// The Pickle's data has a header which contains the size of the Pickle's
// payload.  It can optionally support additional space in the header.  That
// space is controlled by the header_size parameter passed to the Pickle
// constructor.
//
class BASE_EXPORT Pickle {
public:
    // Auxiliary data attached to a Pickle. Pickle must be subclassed along with
    // this interface in order to provide a concrete implementation of support
    // for attachments. The base Pickle implementation does not accept
    // attachments.
    class BASE_EXPORT Attachment : public RefCountedThreadSafe<Attachment> {
    public:
        Attachment();

    protected:
        friend class RefCountedThreadSafe<Attachment>;
        virtual ~Attachment();

        DISALLOW_COPY_AND_ASSIGN(Attachment);
    };

    // Initialize a Pickle object using the default header size.
    Pickle();

    // Initialize a Pickle object with the specified header size in bytes, which
    // must be greater-than-or-equal-to sizeof(Pickle::Header).  The header size
    // will be rounded up to ensure that the header size is 32bit-aligned.
    explicit Pickle(int header_size);

    // Initializes a Pickle from a const block of data.  The data is not copied;
    // instead the data is merely referenced by this Pickle.  Only const methods
    // should be used on the Pickle when initialized this way.  The header
    // padding size is deduced from the data length.
    Pickle(const char* data, int data_len);

    // Initializes a Pickle as a deep copy of another Pickle.
    Pickle(const Pickle& other);

    // Note: There are no virtual methods in this class.  This destructor is
    // virtual as an element of defensive coding.  Other classes have derived from
    // this class, and there is a *chance* that they will cast into this base
    // class before destruction.  At least one such class does have a virtual
    // destructor, suggesting at least some need to call more derived destructors.
    virtual ~Pickle();

    // Performs a deep copy.
    Pickle& operator=(const Pickle& other);

    // Returns the number of bytes written in the Pickle, including the header.
    size_t size() const { return header_size_ + header_->payload_size; }

    // Returns the data for this Pickle.
    const void* data() const { return header_; }

    // Returns the effective memory capacity of this Pickle, that is, the total
    // number of bytes currently dynamically allocated or 0 in the case of a
    // read-only Pickle. This should be used only for diagnostic / profiling
    // purposes.
    size_t GetTotalAllocatedSize() const;

    // Methods for adding to the payload of the Pickle.  These values are
    // appended to the end of the Pickle's payload.  When reading values from a
    // Pickle, it is important to read them in the order in which they were added
    // to the Pickle.

    bool WriteBool(bool value)
    {
        return WriteInt(value ? 1 : 0);
    }
    bool WriteInt(int value)
    {
        return WritePOD(value);
    }
    bool WriteLong(long value)
    {
        // Always write long as a 64-bit value to ensure compatibility between
        // 32-bit and 64-bit processes.
        return WritePOD(static_cast<int64_t>(value));
    }
    bool WriteUInt16(uint16_t value) { return WritePOD(value); }
    bool WriteUInt32(uint32_t value) { return WritePOD(value); }
    bool WriteInt64(int64_t value) { return WritePOD(value); }
    bool WriteUInt64(uint64_t value) { return WritePOD(value); }
    bool WriteFloat(float value)
    {
        return WritePOD(value);
    }
    bool WriteDouble(double value)
    {
        return WritePOD(value);
    }
    bool WriteString(const StringPiece& value);
    bool WriteString16(const StringPiece16& value);
    // "Data" is a blob with a length. When you read it out you will be given the
    // length. See also WriteBytes.
    bool WriteData(const char* data, int length);
    // "Bytes" is a blob with no length. The caller must specify the length both
    // when reading and writing. It is normally used to serialize PoD types of a
    // known size. See also WriteData.
    bool WriteBytes(const void* data, int length);

    // WriteAttachment appends |attachment| to the pickle. It returns
    // false iff the set is full or if the Pickle implementation does not support
    // attachments.
    virtual bool WriteAttachment(scoped_refptr<Attachment> attachment);

    // ReadAttachment parses an attachment given the parsing state |iter| and
    // writes it to |*attachment|. It returns true on success.
    virtual bool ReadAttachment(base::PickleIterator* iter,
        scoped_refptr<Attachment>* attachment) const;

    // Indicates whether the pickle has any attachments.
    virtual bool HasAttachments() const;

    // Reserves space for upcoming writes when multiple writes will be made and
    // their sizes are computed in advance. It can be significantly faster to call
    // Reserve() before calling WriteFoo() multiple times.
    void Reserve(size_t additional_capacity);

    // Payload follows after allocation of Header (header size is customizable).
    struct Header {
        uint32_t payload_size; // Specifies the size of the payload.
    };

    // Returns the header, cast to a user-specified type T.  The type T must be a
    // subclass of Header and its size must correspond to the header_size passed
    // to the Pickle constructor.
    template <class T>
    T* headerT()
    {
        DCHECK_EQ(header_size_, sizeof(T));
        return static_cast<T*>(header_);
    }
    template <class T>
    const T* headerT() const
    {
        DCHECK_EQ(header_size_, sizeof(T));
        return static_cast<const T*>(header_);
    }

    // The payload is the pickle data immediately following the header.
    size_t payload_size() const
    {
        return header_ ? header_->payload_size : 0;
    }

    const char* payload() const
    {
        return reinterpret_cast<const char*>(header_) + header_size_;
    }

    // Returns the address of the byte immediately following the currently valid
    // header + payload.
    const char* end_of_payload() const
    {
        // This object may be invalid.
        return header_ ? payload() + payload_size() : NULL;
    }

protected:
    char* mutable_payload()
    {
        return reinterpret_cast<char*>(header_) + header_size_;
    }

    size_t capacity_after_header() const
    {
        return capacity_after_header_;
    }

    // Resize the capacity, note that the input value should not include the size
    // of the header.
    void Resize(size_t new_capacity);

    // Claims |num_bytes| bytes of payload. This is similar to Reserve() in that
    // it may grow the capacity, but it also advances the write offset of the
    // pickle by |num_bytes|. Claimed memory, including padding, is zeroed.
    //
    // Returns the address of the first byte claimed.
    void* ClaimBytes(size_t num_bytes);

    // Find the end of the pickled data that starts at range_start.  Returns NULL
    // if the entire Pickle is not found in the given data range.
    static const char* FindNext(size_t header_size,
        const char* range_start,
        const char* range_end);

    // Parse pickle header and return total size of the pickle. Data range
    // doesn't need to contain entire pickle.
    // Returns true if pickle header was found and parsed. Callers must check
    // returned |pickle_size| for sanity (against maximum message size, etc).
    // NOTE: when function successfully parses a header, but encounters an
    // overflow during pickle size calculation, it sets |pickle_size| to the
    // maximum size_t value and returns true.
    static bool PeekNext(size_t header_size,
        const char* range_start,
        const char* range_end,
        size_t* pickle_size);

    // The allocation granularity of the payload.
    static const int kPayloadUnit;

private:
    friend class PickleIterator;

    Header* header_;
    size_t header_size_; // Supports extra data between header and payload.
    // Allocation size of payload (or -1 if allocation is const). Note: this
    // doesn't count the header.
    size_t capacity_after_header_;
    // The offset at which we will write the next field. Note: this doesn't count
    // the header.
    size_t write_offset_;

    // Just like WriteBytes, but with a compile-time size, for performance.
    template <size_t length>
    void BASE_EXPORT WriteBytesStatic(const void* data);

    // Writes a POD by copying its bytes.
    template <typename T>
    bool WritePOD(const T& data)
    {
        WriteBytesStatic<sizeof(data)>(&data);
        return true;
    }

    inline void* ClaimUninitializedBytesInternal(size_t num_bytes);
    inline void WriteBytesCommon(const void* data, size_t length);

    FRIEND_TEST_ALL_PREFIXES(PickleTest, DeepCopyResize);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, Resize);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, PeekNext);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, PeekNextOverflow);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNext);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextWithIncompleteHeader);
    FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextOverflow);
};

} // namespace base

#endif // BASE_PICKLE_H_
